<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Eigen: Eigen and multi-threading</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
</script>
<script type="text/javascript" async="async" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="eigendoxy.css" rel="stylesheet" type="text/css">
<!--  -->
<script type="text/javascript" src="eigen_navtree_hacks.js"></script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="Eigen_Silly_Professor_64x64.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname"><a href="http://eigen.tuxfamily.org">Eigen</a>
   &#160;<span id="projectnumber">3.4.90 (git rev 67eeba6e720c5745abc77ae6c92ce0a44aa7b7ae)</span>
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.svg"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('TopicMultiThreading.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title"><a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library.">Eigen</a> and multi-threading </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="TopicMultiThreading_MakingEigenMT"></a>
Make Eigen run in parallel</h1>
<p>Some Eigen's algorithms can exploit the multiple cores present in your hardware. To this end, it is enough to enable OpenMP on your compiler, for instance:</p><ul>
<li>GCC: <code>-fopenmp</code> </li>
<li>ICC: <code>-openmp</code> </li>
<li>MSVC: check the respective option in the build properties.</li>
</ul>
<p>You can control the number of threads that will be used using either the OpenMP API or Eigen's API using the following priority: </p><div class="fragment"><div class="line">OMP_NUM_THREADS=n ./my_program</div>
<div class="line">omp_set_num_threads(n);</div>
<div class="line">Eigen::setNbThreads(n);</div>
</div><!-- fragment --><p> Unless <code>setNbThreads</code> has been called, Eigen uses the number of threads specified by OpenMP. You can restore this behavior by calling <code>setNbThreads(0);</code>. You can query the number of threads that will be used with: </p><div class="fragment"><div class="line">n = Eigen::nbThreads( );</div>
</div><!-- fragment --><p> You can disable Eigen's multi threading at compile time by defining the <a class="el" href="TopicPreprocessorDirectives.html#TopicPreprocessorDirectivesPerformance">EIGEN_DONT_PARALLELIZE </a> preprocessor token.</p>
<p>Currently, the following algorithms can make use of multi-threading:</p><ul>
<li>general dense matrix - matrix products</li>
<li><a class="el" href="classEigen_1_1PartialPivLU.html" title="LU decomposition of a matrix with partial pivoting, and related features.">PartialPivLU</a></li>
<li>row-major-sparse * dense vector/matrix products</li>
<li><a class="el" href="classEigen_1_1ConjugateGradient.html" title="A conjugate gradient solver for sparse (or dense) self-adjoint problems.">ConjugateGradient</a> with <code>Lower|Upper</code> as the <code>UpLo</code> template parameter.</li>
<li><a class="el" href="classEigen_1_1BiCGSTAB.html" title="A bi conjugate gradient stabilized solver for sparse square problems.">BiCGSTAB</a> with a row-major sparse matrix format.</li>
<li><a class="el" href="classEigen_1_1LeastSquaresConjugateGradient.html" title="A conjugate gradient solver for sparse (or dense) least-square problems.">LeastSquaresConjugateGradient</a></li>
</ul>
<dl class="section warning"><dt>Warning</dt><dd>On most OS it is <b>very important</b> to limit the number of threads to the number of physical cores, otherwise significant slowdowns are expected, especially for operations involving dense matrices.</dd></dl>
<p>Indeed, the principle of hyper-threading is to run multiple threads (in most cases 2) on a single core in an interleaved manner. However, Eigen's matrix-matrix product kernel is fully optimized and already exploits nearly 100% of the CPU capacity. Consequently, there is no room for running multiple such threads on a single core, and the performance would drops significantly because of cache pollution and other sources of overheads. At this stage of reading you're probably wondering why Eigen does not limit itself to the number of physical cores? This is simply because OpenMP does not allow to know the number of physical cores, and thus Eigen will launch as many threads as <em>cores</em> reported by OpenMP.</p>
<h1><a class="anchor" id="TopicMultiThreading_UsingEigenWithMT"></a>
Using Eigen in a multi-threaded application</h1>
<p>In the case your own application is multithreaded, and multiple threads make calls to Eigen, then you have to initialize Eigen by calling the following routine <b>before</b> creating the threads: </p><div class="fragment"><div class="line"><span class="preprocessor">#include &lt;Eigen/Core&gt;</span></div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)</div>
<div class="line">{</div>
<div class="line">  Eigen::initParallel();</div>
<div class="line">  </div>
<div class="line">  ...</div>
<div class="line">}</div>
</div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>With Eigen 3.3, and a fully C++11 compliant compiler (i.e., <a href="http://en.cppreference.com/w/cpp/language/storage_duration#Static_local_variables">thread-safe static local variable initialization</a>), then calling <code>initParallel()</code> is optional.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Note that all functions generating random matrices are <b>not</b> re-entrant nor thread-safe. Those include <a class="el" href="classEigen_1_1DenseBase.html#ae814abb451b48ed872819192dc188c19">DenseBase::Random()</a>, and <a class="el" href="classEigen_1_1DenseBase.html#ac476e5852129ba32beaa1a8a3d7ee0db">DenseBase::setRandom()</a> despite a call to <code>Eigen::initParallel()</code>. This is because these functions are based on <code>std::rand</code> which is not re-entrant. For thread-safe random generator, we recommend the use of c++11 random generators (<a class="el" href="classEigen_1_1DenseBase.html#a9752ee59976a4b4aad860ad1a9093e7f">example </a>) or <code>boost::random</code>.</dd></dl>
<p>In the case your application is parallelized with OpenMP, you might want to disable Eigen's own parallelization as detailed in the previous section.</p>
<dl class="section warning"><dt>Warning</dt><dd>Using OpenMP with custom scalar types that might throw exceptions can lead to unexpected behaviour in the event of throwing. </dd></dl>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Thu Apr 21 2022 13:07:55 for Eigen by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li>
  </ul>
</div>
</body>
</html>
